1
Game.Core.Primitives        ← 原子层
2
        ↓
3
Game.ModApi                 ← 公共契约
4
        ↓
5
Game.Core.Context/Rules/Networking/Persistence/HotUpdate/Diagnostics
6
        ↓
7
Game.Bootstrap              ← 组合根（这一篇）

1
Bootstrap/
2
├── ApplicationLifecycleCoordinator.cs   (247 行) ← App 级生命周期
3
├── AppLifetimeScope.cs                  (63 行)  ← VContainer 配置入口
4
├── AppLifetimeScope.prefab              (1 个 MonoBehaviour 挂载点)
5
├── AssemblyInfo.cs                      (4 行)  ← InternalsVisibleTo 测试程序集
6
├── EntryPointFailureReporter.cs         (31 行) ← VContainer entry-point 异常 → 诊断
7
├── FrameworkCompatibilityConfiguration.cs (19 行) ← ScriptableObject → FrameworkCompatibility
8
├── FrameworkIdentityProvider.cs         (10 行) ← 暴露兼容性信息
9
├── IFrameworkIdentityProvider.cs        (9 行)
10
├── ModuleDiagnosticsAdapter.cs          (59 行) ← IModuleDiagnostics 适配器
11
│
12
├── Session/
13
│   ├── ISession.cs                      (15 行) ← IAsyncDisposable + Start/Stop
14
│   ├── ISessionFactory.cs               (9 行)
15
│   ├── Session.cs                       (420 行) ← Session 实现（核心）
16
│   ├── SessionFactory.cs                (89 行) ← Session 工厂 + latch
17
│   ├── SessionLifetime.cs               (46 行) ← 不可变 Session 视图
18
│   ├── SessionState.cs                  (12 行) ← 状态枚举
19
│   └── VContainerSessionScopeFactory.cs (73 行) ← 实际 VContainer 集成
20
│
21
└── Threading/
22
    └── UnityMainThreadGuard.cs          (77 行) ← 主线程守门（核心）

1
Core/Diagnostics/
2
├── DiagnosticRouter.cs             ← 路由到多个 sink，捕获 sink 异常
3
├── DiagnosticEventFactory.cs       ← 把 10 个字段打包成 DiagnosticEvent
4
├── FrameworkDiagnosticEvents.cs    ← 10 个标准事件名常量
5
├── IDiagnosticSink.cs              ← sink 接口
6
├── InMemoryDiagnosticSink.cs       ← 测试用 sink
7
├── UnityConsoleDiagnosticSink.cs   ← 把事件写到 Unity 控制台
8
└── (1 个 README)

1
AppLifetimeScope (Unity MonoBehaviour)
2
    │ VContainer Configure
3
    ↓
4
registers: IUnityMainThreadGuard, SessionFactory, DiagnosticRouter, ...
5
    │
6
    ↓
7
ApplicationLifecycleCoordinator (VContainer EntryPoint)
8
    │ owns
9
    ↓
10
SessionFactory
11
    │ creates
12
    ↓
13
Session
14
    │ owns
15
    ↓
16
VContainerSessionScope (child VContainer scope)
17
    │
18
    ↓
19
SessionLifetime (immutable view, exposed to services)

1
public sealed class AppLifetimeScope : LifetimeScope
2
{
3
    [SerializeField] FrameworkCompatibilityConfiguration compatibilityConfiguration;
4

5
    protected override void Configure(IContainerBuilder builder)
6
    {
7
        var mainThreadGuard = UnityMainThreadGuard.CaptureCurrentThread();
8
        // ... 验证 compatibility、注册服务
9
    }
10
}

1
// 来自 UnityMainThreadGuard 的注释：
2
// "its identity is captured inside AppLifetimeScope.Configure,
3
//  which VContainer runs during composition on the Unity main thread;
4
//  it is never guessed from a static initializer, which would latch
5
//  whichever thread first touched the type"

1
// ❌ 错误做法：static init 捕获
2
public static readonly UnityMainThreadGuard Instance =
3
    new UnityMainThreadGuard(Thread.CurrentThread.ManagedThreadId);
4
//    ↑ 第一次访问这个类型的线程就是"主线程"——但这是错的
5
//       如果 test runner 的某个 background task 先 touch，guard 就废了

1
var consoleSink = new UnityConsoleDiagnosticSink();
2
var router = new DiagnosticRouter(new[] { consoleSink });
3
var eventFactory = new DiagnosticEventFactory();
4
compatibility = compatibilityConfiguration.ToRuntime();
5

6
var identity = new FrameworkIdentityProvider(compatibility);
7
var failureReporter = new EntryPointFailureReporter(router, eventFactory);
8

9
builder.RegisterInstance<IUnityMainThreadGuard>(mainThreadGuard);
10
builder.RegisterInstance(compatibility);
11
builder.RegisterInstance(router);
12
builder.RegisterInstance(eventFactory);
13
builder.RegisterInstance<IFrameworkIdentityProvider>(identity);
14
builder.Register<ModuleDiagnosticsAdapterFactory>(Lifetime.Singleton);
15
builder.Register<VContainerSessionScopeFactory>(Lifetime.Singleton).As<ISessionScopeFactory>();
16
builder.Register<SessionFactory>(Lifetime.Singleton).AsSelf().As<ISessionFactory>();
17
builder.RegisterInstance(failureReporter);
18
builder.RegisterEntryPointExceptionHandler(failureReporter.Report);
19
builder.RegisterEntryPoint<ApplicationLifecycleCoordinator>();

1
builder.RegisterEntryPointExceptionHandler(failureReporter.Report);
2
builder.RegisterEntryPoint<ApplicationLifecycleCoordinator>();

1
// VContainer/Runtime/Unity/ContainerBuilderUnityExtensions.cs:13-26
2
public static void EnsureDispatcherRegistered(IContainerBuilder containerBuilder)
3
{
4
    if (containerBuilder.Exists(typeof(EntryPointDispatcher), false)) return;
5
    containerBuilder.Register<EntryPointDispatcher>(Lifetime.Scoped);
6

7
    if (!containerBuilder.Exists(typeof(EntryPointExceptionHandler)))                          // ★
8
        containerBuilder.RegisterEntryPointExceptionHandler(UnityEngine.Debug.LogException);   // ★ 默认 handler
9

10
    containerBuilder.RegisterBuildCallback(container =>
11
        container.Resolve<EntryPointDispatcher>().Dispatch());
12
}

1
FrameworkCompatibility compatibility;
2
try
3
{
4
    if (compatibilityConfiguration == null)
5
        throw new System.InvalidOperationException("AppLifetimeScope requires a compatibility configuration asset.");
6
    compatibility = compatibilityConfiguration.ToRuntime();
7
}
8
catch (System.Exception exception)
9
{
10
    router.Emit(eventFactory.Create(
11
        DiagnosticSeverity.Critical,
12
        FrameworkDiagnosticEvents.ApplicationStartFailed,
13
        CorrelationId.New(),
14
        lifecycleEpisodeId: LifecycleEpisodeId.New(),
15
        error: new DiagnosticError(
16
            "framework.configuration-invalid",
17
            ...)));
18
    throw;  // ← 关键：抛回去，让 VContainer 也报告失败
19
}

1
builder.Register<VContainerSessionScopeFactory>(Lifetime.Singleton).As<ISessionScopeFactory>();   // 没有 AsSelf
2
builder.Register<SessionFactory>(Lifetime.Singleton).AsSelf().As<ISessionFactory>();              // 有 AsSelf

1
// ApplicationLifecycleCoordinator.cs:51-55
2
internal ApplicationLifecycleCoordinator(
3
    DiagnosticRouter router,
4
    DiagnosticEventFactory eventFactory,
5
    SessionFactory sessionFactory,          // ← 具体类型，不是 ISessionFactory
6
    IUnityMainThreadGuard mainThread)

1
public interface ISessionFactory
2
{
3
    bool HasActiveSession { get; }
4
    ISession ActiveSession { get; }
5
    ISession CreateSession();
6
    // 没有 PreventNewSessions
7
}

1
LifetimeScope.Awake / Build
2
  → ContainerBuilder.Build()
3
      → RegisterBuildCallback 里的 container.Resolve<EntryPointDispatcher>().Dispatch()
4
          → PlayerLoopHelper.EnsureInitialized()
5
          → container.ResolveOrDefault<EntryPointExceptionHandler>()      ← handler 在这里才解析
6
          → PlayerLoopHelper.Dispatch(PlayerLoopTiming.Startup, startableLoopItem)
7
                    ↓
8
              【下一次 Unity PlayerLoop 的 Startup 阶段】
9
                    ↓
10
              ApplicationLifecycleCoordinator.Start()

1
internal interface IUnityMainThreadGuard
2
{
3
    bool IsMainThread { get; }
4
    void ThrowIfNotMainThread(string operation);
5
    InvalidOperationException CreateViolation(string operation);  // 不抛，只构造
6
}

1
/// Internal to Game.Bootstrap. It is never exposed through Game.ModApi or the
2
/// distributed Mod SDK, and it deliberately does not live in Game.Core.Primitives:
3
/// it exists only because this assembly creates and disposes Unity and VContainer objects.

1
/// The main thread identity is captured during App composition — AppLifetimeScope runs
2
/// Configure on the Unity main thread — and never guessed from a static initializer,
3
/// which could latch whichever thread happened to touch the type first.

1
/// Each App root receives a fresh instance, so the policy stays correct when Domain Reload
2
/// is disabled.

1
return new InvalidOperationException(
2
    $"{operation} must be initiated on the Unity main thread. Application and Session " +
3
    "lifecycle mutation creates and disposes Unity and VContainer objects, so it is " +
4
    "main-thread-only and is never dispatched through Task.Run or a thread-pool continuation.");

1
public enum SessionState
2
{
3
    Created = 0,
4
    Starting = 1,
5
    Running = 2,
6
    Stopping = 3,
7
    Stopped = 4,
8
    Failed = 5,
9
}

1
                  StartAsync
2
        Created ──────────────→ Starting ────────→ Running
3
            │                   (建立 scope)        │
4
            │ StopAsync        │                  StopAsync
5
            ├─────────────────→ ┤ Stopping ←────── ┤
6
            │                  ↓                   │
7
            │                 [清理]               │
8
            ↓                  ↓                   ↓
9
          Failed (各种失败路径)               Stopped

1
public Task StopAsync(CancellationToken cancellationToken)
2
{
3
    if (!mainThread.IsMainThread)                              // ← 不在锁里
4
        return Task.FromException(...);
5

6
    TaskCompletionSource<bool> completion;
7
    lock (sync)                                                // ← 锁内只做状态变更 + memoization
8
    {
9
        if (stopTask != null) return stopTask;
10
        if (state == SessionState.Failed || state == SessionState.Stopped)
11
        {
12
            isDisposed = true;
13
            return stopTask = Task.CompletedTask;
14
        }
15
        state = SessionState.Stopping;
16
        completion = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
17
        stopTask = completion.Task;
18
    }
19

20
    RunStop(completion);                                       // ← 锁外做 cancel + dispose + release
21
    return stopTask;
22
}

1
const int callers = 16;
2
var results = new Task[callers];
3
for (var index = 0; index < callers; index++)
4
    results[index] = session.StopAsync(CancellationToken.None);
5
await Task.WhenAll(results);
6

7
Assert.That(results.Distinct().Count(), Is.EqualTo(1), "Every caller must observe the same operation.");

1
lock (sync)
2
{
3
    if (stopTask != null) return stopTask;  // ← 第二个 caller 拿到第一个的 Task
4
    // ...
5
    stopTask = completion.Task;             // ← 第一个 caller memoize
6
}

1
public Task StartAsync(CancellationToken cancellationToken)
2
{
3
    // ...
4
    lock (sync)
5
    {
6
        if (isDisposed) return Task.FromException(new ObjectDisposedException(nameof(Session)));
7
        if (state != SessionState.Created)
8
            return Task.FromException(new InvalidOperationException(...));
9
        state = SessionState.Starting;
10
    }
11

12
    Emit(SessionStarting);
13
    try
14
    {
15
        cancellationToken.ThrowIfCancellationRequested();
16
        var created = scopeFactory.Create(lifetime);
17

18
        // ★ 关键：scope 已建好，但还需要 re-check state
19
        bool adopted;
20
        lock (sync)
21
        {
22
            adopted = state == SessionState.Starting;
23
            if (adopted) scope = created;
24
        }
25

26
        if (!adopted)
27
        {
28
            DisposeSupersededScope(created);        // ← 有人在我们建 scope 时 stop 了
29
            return Task.FromCanceled(new CancellationToken(true));
30
        }
31
        // ...
32
    }
33
}

1
void FailStart(Exception primary)
2
{
3
    Exception cleanupFailure = null;
4
    try
5
    {
6
        try { lifetimeCancellation.Cancel(); }
7
        catch (Exception exception) { cleanupFailure = exception; }
8

9
        ISessionScope ownedScope;
10
        lock (sync)
11
        {
12
            ownedScope = scope;
13
            scope = null;
14
        }
15

16
        try { ownedScope?.Dispose(); }
17
        catch (Exception exception) { cleanupFailure = cleanupFailure ?? exception; }
18

19
        try { release(this); }
20
        catch (Exception exception) { cleanupFailure = cleanupFailure ?? exception; }
21
    }
22
    finally
23
    {
24
        lock (sync)
25
        {
26
            state = SessionState.Failed;
27
            isDisposed = true;
28
            if (stopTask == null) stopTask = Task.CompletedTask;
29
        }
30
        DisposeCancellationOnce();
31
    }
32

33
    Emit(Severity.Error, SessionFailed, BuildError("framework.session-start-failed", primary, cleanupFailure));
34
}

1
catch (Exception exception)
2
{
3
    cleanupFailure = cleanupFailure ?? exception;  // ← 用 ?? 而不是 =
4
}

1
finally
2
{
3
    lock (sync)
4
    {
5
        state = SessionState.Failed;        // ← 无论 throw 没 throw 都跑
6
        isDisposed = true;
7
        if (stopTask == null) stopTask = Task.CompletedTask;
8
    }
9
    DisposeCancellationOnce();
10
}

1
static DiagnosticError BuildError(string code, Exception primary, Exception cleanupFailure)
2
{
3
    var message = Describe(primary);
4
    if (cleanupFailure != null)
5
        message = $"{message} (cleanup also failed: {cleanupFailure.GetType().FullName}: {Describe(cleanupFailure)})";
6
    return new DiagnosticError(code, message, primary.GetType().FullName);
7
}
8

9
static string Describe(Exception exception) =>
10
    string.IsNullOrWhiteSpace(exception.Message) ? exception.GetType().Name : exception.Message;

1
void DisposeCancellationOnce()
2
{
3
    lock (sync)
4
    {
5
        if (cancellationDisposed) return;
6
        cancellationDisposed = true;
7
    }
8
    lifetimeCancellation.Dispose();
9
}

1
// Session.cs:86
2
lifetime = new SessionLifetime(id, lifetimeCancellation.Token);   // ← 构造时抓一次，之后再不碰 source

1
// SessionTestSupport.cs:67
2
TokenCancelledAtDispose = Lifetime != null && Lifetime.Token.IsCancellationRequested;

1
public ISession CreateSession()
2
{
3
    mainThread.ThrowIfNotMainThread(...);
4
    lock (sync)
5
    {
6
        if (creationPrevented)
7
            throw new InvalidOperationException("The application is shutting down; no new Session may be created.");
8
        if (activeSession != null)
9
            throw new InvalidOperationException("Only one Session may be active at a time.");
10
        activeSession = new Session(...);
11
        return activeSession;
12
    }
13
}

1
internal void PreventNewSessions()
2
{
3
    mainThread.ThrowIfNotMainThread(...);
4
    lock (sync) creationPrevented = true;
5
}

1
public ISession CreateSession()
2
{
3
    // ...
4
    activeSession = new Session(..., Release);
5
    // ...
6
}
7

8
void Release(Session session)
9
{
10
    lock (sync)
11
    {
12
        if (ReferenceEquals(activeSession, session)) activeSession = null;
13
    }
14
}

1
internal interface ISessionLifetime
2
{
3
    SessionId SessionId { get; }
4
    CancellationToken Token { get; }
5
}
6

7
sealed class SessionLifetime : ISessionLifetime
8
{
9
    internal SessionLifetime(SessionId sessionId, CancellationToken token)
10
    {
11
        if (!sessionId.IsValid) throw new ArgumentException(...);
12
        SessionId = sessionId;
13
        Token = token;
14
    }
15

16
    public SessionId SessionId { get; }
17
    public CancellationToken Token { get; }
18
}

1
internal SessionLifetime(SessionId sessionId, CancellationToken token)
2
{
3
    // ...
4
    Token = token;
5
}

1
public ISessionScope Create(ISessionLifetime lifetime)
2
{
3
    // ...
4
    var child = appScope.CreateChild(
5
        builder =>
6
        {
7
            builder.RegisterInstance(sessionId);
8
            builder.RegisterInstance<ISessionLifetime>(lifetime);
9
        },
10
        $"Session {sessionId}");
11
    return new VContainerSessionScope(child, mainThread);
12
}

1
public class MyService
2
{
3
    public MyService(SessionId sessionId, ISessionLifetime lifetime)
4
    {
5
        _sessionId = sessionId;
6
        _token = lifetime.Token;  // 用来观察 Session 是否要停了
7
    }
8
}

1
public ISessionScope Create(ISessionLifetime lifetime)
2
{
3
    mainThread.ThrowIfNotMainThread(nameof(VContainerSessionScopeFactory) + "." + nameof(Create));
4
    // ...
5
    var child = appScope.CreateChild(...);
6
    return new VContainerSessionScope(child, mainThread);
7
}
8

9
sealed class VContainerSessionScope : ISessionScope
10
{
11
    public void Dispose()
12
    {
13
        mainThread.ThrowIfNotMainThread("Session child scope disposal");
14
        // ...
15
    }
16
}

1
sealed class VContainerSessionScope : ISessionScope
2
{
3
    public bool IsDisposed => scope == null;
4

5
    public void Dispose()
6
    {
7
        mainThread.ThrowIfNotMainThread("Session child scope disposal");
8
        var owned = scope;
9
        scope = null;
10
        owned?.Dispose();
11
    }
12
}

1
public sealed class ApplicationLifecycleCoordinator : IStartable, IDisposable

1
public Task ShutdownAsync(CancellationToken cancellationToken)
2
{
3
    if (!mainThread.IsMainThread)
4
        return Task.FromException(...);
5

6
    TaskCompletionSource<bool> completion;
7
    lock (sync)
8
    {
9
        if (shutdownTask != null) return shutdownTask;        // ← 幂等
10
        completion = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
11
        shutdownTask = completion.Task;
12
    }
13

14
    RunShutdown(completion);
15
    return shutdownTask;
16
}

1
void RunShutdown(TaskCompletionSource<bool> completion)
2
{
3
    Emit(ApplicationStopping);
4

5
    SessionFactory factory;
6
    lock (sync) factory = sessionFactory;       // ← 锁外 snapshot 引用
7

8
    ISession active = null;
9
    try
10
    {
11
        if (factory != null)
12
        {
13
            factory.PreventNewSessions();        // ① 锁新 Session
14
            active = factory.ActiveSession;      // ② 取现有 Session
15
        }
16
    }
17
    catch (Exception exception)
18
    {
19
        CompleteShutdown(completion, exception);
20
        return;
21
    }
22

23
    if (active == null)
24
    {
25
        CompleteShutdown(completion, null);
26
        return;
27
    }
28

29
    Task stop;
30
    try
31
    {
32
        stop = active.StopAsync(CancellationToken.None);   // ③ 停止 Session
33
    }
34
    catch (Exception exception)
35
    {
36
        CompleteShutdown(completion, exception);
37
        return;
38
    }
39

40
    if (stop.IsCompleted)                                       // ④ sync 完成
41
    {
42
        CompleteShutdown(completion, Failure(stop));
43
        return;
44
    }
45

46
    stop.ContinueWith(                                          // ⑤ async 完成
47
        completed => CompleteShutdown(completion, Failure(completed)),
48
        CancellationToken.None,
49
        TaskContinuationOptions.ExecuteSynchronously,
50
        TaskScheduler.Default);                                 // ← 显式线程池！
51
}

1
public void Dispose()
2
{
3
    mainThread.ThrowIfNotMainThread(...);
4

5
    Task pending;
6
    lock (sync) pending = shutdownTask;
7
    pending = pending ?? ShutdownAsync(CancellationToken.None);    // ← 触发 shutdown 如果还没
8

9
    if (pending.IsCompleted)
10
    {
11
        if (pending.IsFaulted) _ = pending.Exception;             // ← observe 故障
12
        return;
13
    }
14

15
    Emit(Warning, ApplicationStopped,
16
        new DiagnosticError("framework.application-shutdown-incomplete",
17
            "The application root was disposed before asynchronous Session shutdown completed; call ShutdownAsync and await it before disposing the root."));
18
}

1
if (pending.IsFaulted) _ = pending.Exception;

1
public void Emit(DiagnosticEvent diagnosticEvent)
2
{
3
    foreach (var sink in sinks)
4
    {
5
        try
6
        {
7
            sink.Write(diagnosticEvent);
8
        }
9
        catch (Exception exception)
10
        {
11
            try
12
            {
13
                sinkFailureHandler(exception);
14
            }
15
            catch (Exception handlerException)
16
            {
17
                UnityEngine.Debug.LogException(handlerException);
18
            }
19
        }
20
    }
21
}

1
this.sinkFailureHandler = sinkFailureHandler ?? UnityEngine.Debug.LogException;

1
// Core/Diagnostics/InMemoryDiagnosticSink.cs:12-21
2
public IReadOnlyList<DiagnosticEvent> Snapshot
3
{
4
    get { lock (sync) { return events.ToArray(); } }
5
}

1
// DiagnosticRouter.cs:16-18
2
this.sinks = sinks.ToArray();
3
if (this.sinks.Any(sink => sink == null))
4
    throw new ArgumentException("Diagnostic sink collection cannot contain null entries.", nameof(sinks));

1
// Bootstrap/ModuleDiagnosticsAdapter.cs:1-3
2
using Game.Core.Diagnostics;      // DiagnosticRouter、DiagnosticEventFactory（私有实现侧）
3
using Game.Core.Primitives;
4
using Game.ModApi.Diagnostics;    // IModuleDiagnostics、ModuleDiagnostic（公共契约侧）

1
// SessionStateMachineTests.cs:53-74
2
var activeAtStoppedEvent = true;
3
SessionFactory factory = null;
4
var observer = new DelegateSink(value =>
5
{
6
    if (value.Name == FrameworkDiagnosticEvents.SessionStopped)
7
        activeAtStoppedEvent = factory.HasActiveSession;      // ← 在事件回调里回头看工厂
8
});
9
...
10
await session.StopAsync(CancellationToken.None);
11

12
Assert.That(scopeFactory.Created.Single().IsDisposed, Is.True);
13
Assert.That(activeAtStoppedEvent, Is.False);                  // ★ 关键断言
14
Assert.That(memory.Snapshot.Select(value => value.Name), Is.EqualTo(new[]
15
{
16
    FrameworkDiagnosticEvents.SessionStarting,
17
    FrameworkDiagnosticEvents.SessionStarted,
18
    FrameworkDiagnosticEvents.SessionStopping,
19
    FrameworkDiagnosticEvents.SessionStopped,
20
}));

1
sink.On(SessionStopped, () => factory.CreateSession());   // 合法吗？

1
// Session.cs:353-362
2
finally
3
{
4
    lock (sync)
5
    {
6
        state = SessionState.Failed;   // ← 取消也走这里，没有分支
7
        isDisposed = true;
8
        if (stopTask == null) stopTask = Task.CompletedTask;
9
    }
10
    DisposeCancellationOnce();
11
}

1
// SessionStateMachineTests.cs:92-95
2
Assert.That(async () => await session.StartAsync(cancellation.Token),
3
    Throws.InstanceOf<OperationCanceledException>());
4
Assert.That(session.State, Is.EqualTo(SessionState.Failed));   // ← 不是 Stopped

1
// Session.cs:176-185
2
catch (Exception exception)
3
{
4
    FailStart(exception);                                    // 状态：一律 Failed
5
    if (exception is OperationCanceledException)
6
    {
7
        var token = cancellationToken.IsCancellationRequested ? cancellationToken : new CancellationToken(true);
8
        return Task.FromCanceled(token);                     // ← 结果：Canceled
9
    }
10
    return Task.FromException(exception);                    // ← 结果：Faulted
11
}

1
public Exception CreateFailure { get; set; }               // 从 Create() 抛 → 连 scope 都建不出来
2
public Exception DisposeFailure { get; set; }              // 传给 RecordingScope，从它的 Dispose() 抛
3
public Action<ISessionLifetime> OnCreating { get; set; }   // Create() 最开始的回调 → 注入重入/取消
4

5
public ISessionScope Create(ISessionLifetime lifetime)
6
{
7
    OnCreating?.Invoke(lifetime);                          // ① 先回调
8
    if (CreateFailure != null) throw CreateFailure;        // ② 再决定要不要炸
9
    var scope = new RecordingScope(lifetime, DisposeFailure);   // ③ DisposeFailure 在这里被"冻结"进 scope
10
    Created.Add(scope);
11
    return scope;
12
}

1
public int DisposeCount { get; private set; }              // 证明"恰好释放一次"
2
public bool TokenCancelledAtDispose { get; private set; }  // 证明"cancel 早于 dispose"
3
public bool IsDisposed { get; private set; }

1
// SessionCleanupFailureTests.cs:93-125
2
[Test]
3
public void Failed_start_preserves_the_primary_failure_when_cleanup_also_throws()
4
{
5
    var harness = new SessionTestHarness();
6
    harness.ScopeFactory.DisposeFailure = new InvalidOperationException("scope dispose failed");
7
    var session = harness.Factory.CreateSession();
8
    using var cancellation = new CancellationTokenSource();
9

10
    // 在 scope 建出来之后才取消，这样失败清理路径上"有东西可 dispose"
11
    harness.ScopeFactory.OnCreating = _ => cancellation.Cancel();
12

13
    Assert.That(
14
        async () => await session.StartAsync(cancellation.Token),
15
        Throws.InstanceOf<OperationCanceledException>(),          // ★ 主失败原样传播
16
        "The primary start failure must not be replaced by the cleanup failure.");
17

18
    var failure = harness.Memory.Snapshot.Last();
19
    Assert.That(failure.Error.Value.Code, Is.EqualTo("framework.session-start-failed"));
20
    Assert.That(failure.Error.Value.ExceptionType,
21
        Does.Contain("OperationCanceledException"));               // ★ 主失败类型进 ExceptionType
22
    Assert.That(failure.Error.Value.Message,
23
        Does.Contain("scope dispose failed"));                     // ★ 清理失败拼进 Message
24
}

1
static T OnWorkerThread<T>(Func<T> function)
2
{
3
    var result = default(T);
4
    var failure = OnWorkerThread(() => { result = function(); });
5
    Assert.That(failure, Is.Null, "This lifecycle method must fault its operation rather than throw synchronously.");
6
    return result;
7
}

1
// The factory is neither poisoned nor latched: the main thread still works.
2
Assert.That(() => harness.Factory.CreateSession(), Throws.Nothing);

1
const int callers = 16;
2
var ready = new ManualResetEventSlim(false);
3
var rejected = new Task[callers];
4
var threads = new Thread[callers];
5
for (var index = 0; index < callers; index++)
6
{
7
    var slot = index;
8
    threads[slot] = new Thread(() =>
9
    {
10
        ready.Wait();
11
        rejected[slot] = session.StopAsync(CancellationToken.None);
12
    }) { IsBackground = true };
13
    threads[slot].Start();
14
}
15
ready.Set();
16
foreach (var thread in threads)
17
    Assert.That(thread.Join(TimeSpan.FromSeconds(10)), Is.True, "Rejection must not deadlock.");

1
var reentrantSink = new DelegateDiagnosticSink(recorded =>
2
{
3
    if (session == null) return;
4
    observed.Add(session.State);                // ← 从 sink 里读 Session
5
    observedIds.Add(session.Id);
6

7
    var probe = new Thread(() =>                // ← 跨线程读
8
    {
9
        var _ = session.State;
10
        var __ = session.Id;
11
    }) { IsBackground = true, Name = "diagnostic-lock-probe" };
12
    probe.Start();
13
    if (probe.Join(TimeSpan.FromSeconds(5))) crossThreadReads++;
14
    else crossThreadTimeouts++;
15
});
16

17
var harness = new SessionTestHarness(reentrantSink);
18
session = harness.Factory.CreateSession();
19

20
await session.StartAsync(CancellationToken.None);
21
await session.StopAsync(CancellationToken.None);
22

23
Assert.That(crossThreadTimeouts, Is.Zero, "No lifecycle lock may be held while a diagnostic sink runs.");

1
for (var index = 0; index < 20; index++)
2
{
3
    var session = harness.Factory.CreateSession();
4
    await session.StartAsync(CancellationToken.None);
5
    await session.StopAsync(CancellationToken.None);
6
    // ...
7
}
8

9
Assert.That(harness.ScopeFactory.Created, Has.Count.EqualTo(20));
10
Assert.That(harness.ScopeFactory.Created.All(scope => scope.IsDisposed), Is.True);
11
Assert.That(harness.ScopeFactory.Created.All(scope => scope.DisposeCount == 1), Is.True);

1
lock (sync)
2
{
3
    if (stopTask != null) return stopTask;   // ← 第二个 caller 拿第一个的 Task
4
    // ...
5
}

1
catch (Exception exception)
2
{
3
    cleanupFailure = cleanupFailure ?? exception;  // ← 不覆盖
4
}

1
try { /* cleanup */ }
2
finally { state = ...; isDisposed = true; }